Logging

Use the Kanzi logging system to print messages to the Log window, the Kanzi debug console, standard output, and the system log on your target device. For example, use logging to find problems in your Kanzi application, and to inform the user about the status of your application.

You can:

Print log messages using the Kanzi logging macros. See Printing log messages.
Use log levels to show log messages based on their severity. See Setting the log level.
Use log categories to group log messages that contain information related to specific functionality. See Using log categories.

Printing log messages

Use the Kanzi logging macros to print messages to the log. Most of the logging macros use a fixed log level to indicate the severity of the information in the message. See Setting the log level.

TIP

Do not use application critical code in the logging macro calls. If you place application critical code as an argument to the logging macro call, and during compilation you disable the log level or the log category assigned to the message in the call, the preprocessor removes the logging macro call together with the application critical code.

Kanzi has these logging macros:

Logging macro	Description
`kzLogError`	Log error messages using the Default Logger (`DefaultLogger`), the `error` (`KZ_LOG_LEVEL_ERROR`) log level, and the log category that you provide as an input parameter.
`kzLogWarning`	Log warning messages using the Default Logger (`DefaultLogger`), the `warning` (`KZ_LOG_LEVEL_WARNING`) log level, and the log category that you provide as an input parameter.
`kzLogInfo`	Log info messages using the Default Logger (`DefaultLogger`), the `info` (`KZ_LOG_LEVEL_INFO`) log level, and the log category that you provide as an input parameter.
`kzLogTrace`	Log trace messages using the Default Logger (`DefaultLogger`), the `trace` (`KZ_LOG_LEVEL_TRACE`) log level, and the log category that you provide as an input parameter.
`kzLogDebug`	Log debug messages using the Default Logger (`DefaultLogger`), the `info` (`KZ_LOG_LEVEL_INFO`) log level, and the log category `KZ_LOG_CATEGORY_DEBUG`.
`kzLog`	Log messages using a custom logger, and the log level and category that you provide as input parameters.

To print log messages:

In your application code, use a logging macro where you want to print a log message.
For example:

Debug macro:

// Print "This is a debug message.".
kzLogDebug(("This is a debug message."));

Prints to the log:

info:debug> This is a debug message.

Error macro:

// Print "This is an error message." using the log category MY_LOG_CATEGORY.
// Use log categories to group your log messages based on the functionality to which they are related. See Using log categories.
kzLogError(MY_LOG_CATEGORY, ("This is an error message."));

Prints to the log the path to the file, the line number where the error originated, and the error message:

error:My category:c:\kanziworkspace\projects\myproject\application\src\myproject.cpp:196> This is an error message.

Info macro:

// Print "1 plus 2 equals 3." using the log category MY_LOG_CATEGORY. See Using log categories.
kzLogInfo(MY_LOG_CATEGORY, ("{} plus {} equals {}.", 1, 2, 1+2));
int length = 100;
// Print "The length is 100.".
kzLogInfo(MY_LOG_CATEGORY, ("The length is {}.", length));

Prints to the log:

info:My category> 1 plus 2 equals 3.
info:My category> The length is 100.

Build and run your application. See Deploying Kanzi applications.
For example, on Windows build your application in Visual Studio using the GL_vs2015_Debug build configuration. When you run the application and reach in the code the point where you call the logging macro, Kanzi prints the message to the debug console.

Setting the log level

Use log levels to show log messages based on their severity. For example, to log critical issues during application execution, use the error log level.

The Kanzi logging system has these log levels:

Log level	Name	Severity	Description
`KZ_LOG_LEVEL_ERROR`	`error`	1	Logs critical malfunction messages. Create detailed error messages so that you can receive enough information about an issue.
`KZ_LOG_LEVEL_WARNING`	`warning`	2	Logs facts that require attention, which are not necessarily malfunctions. For example, use a warning message to notify the user about an outcome from which the application can recover, such as a missing parameter that has a default value, or an event that can lead to performance degradation, but is not a failure.
`KZ_LOG_LEVEL_INFO`	`info`	3	Logs information that gives a brief overview of what is happening in the system, log states passed, static information about configuration, and so on.
`KZ_LOG_LEVEL_TRACE`	`trace`	4	Logs the maximum amount of information about the system. This is the most verbose log level. Use this level to troubleshoot issues.

These log levels are enabled by default:

To set the log level, use the KZ_LOG_LEVEL_ENABLED_THRESHOLD macro.
For example, to set a log level that enables all log levels:

#define KZ_LOG_LEVEL_ENABLED_THRESHOLD KZ_LOG_LEVEL_TRACE

You can create you own log levels. See KZ_LOG_CREATE_LEVEL.

Using log categories

Use log categories to group log messages that contain information related to specific functionality.

The Kanzi logging system has these default log categories:

Log category	Description
`KZ_LOG_CATEGORY_DEBUG`	Collects debug messages.
`KZ_LOG_CATEGORY_GRAPHICS_MESH_EXTRA`	Collects graphics mesh log messages.
`KZ_LOG_CATEGORY_EGL_EXTRA`	Collects EGL log messages.
`KZ_LOG_CATEGORY_GENERIC`	Collects log messages that you have not assigned to any other log category. It is recommended to always explicitly assign a log message to one of the log categories, or create a new log category.

To create and use a log category:

Create a log category with the KZ_LOG_CREATE_CATEGORY macro:

// Create a log category named "My category" and set the state of the category to enabled.
// The Kanzi logging system uses category state to filter log messages.
// To disable a log category, use KZ_LOG_DISABLED_CATEGORY.
#define MY_LOG_CATEGORY    KZ_LOG_CREATE_CATEGORY(KZ_LOG_ENABLED_CATEGORY, "My category")

Print a log message in the log category that you created:

// Print to the log "This is an info message." using the MY_LOG_CATEGORY log category.
kzLogInfo(MY_LOG_CATEGORY, ("This is an info message."));

Build and run your application or interact with your application in the Kanzi Studio Preview. When your application reaches the code where you created the log message, Kanzi prints the message to the debug console or to the Kanzi Studio Log window:
```
info:My category> This is an info message.
```

Logging

Printing log messages

Setting the log level

Using log categories

See also